feat(plugins): manual-pages flow — manpage seed schema, flow docs, verification fixes#971
Merged
Conversation
The bundled markdown for both tools carries a {{OSS_DISCOUNT_CODE}}
placeholder, and the tools returned it verbatim — users saw the literal
template string. The prior test asserted the placeholder, pinning the bug.
Substitute the code from cli.promo (single source of truth) on read, and
assert that no template braces ever reach tool output.
Fixes #958. Found during live verification for #952.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
…ch total semantics - README, Docker guide, and character-handling guide referenced 'basic-memory sync', which no longer exists; point them at 'basic-memory reindex' (the incremental filesystem scan) instead. Part of #959. - Document in the search_notes docstring that vector/hybrid searches report total: 0 by design (no second counting pass) and that has_more is the pagination signal in those modes. Found during live verification for #952. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
Picoschema for Unix-style manual pages as Basic Memory notes (#952): section/name/summary/verified frontmatter contracts, gotcha/bug/pattern observation categories, see_also relations. Opt-in seed — not wired into bm-setup's default seeding; documentation projects adopt it explicitly. Validated by just package-check-claude-code. The first consumer is the 'manual' project in the Basic Memory team workspace: 38 pages validating 38/38 against this schema. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
What the manual is (notes conforming to the Manpage schema, SEE ALSO as relations), where it lives (team-workspace 'manual' project; opt-in seed schema for any project), the verification discipline (examples must run, playground rule, verified stamps, schema-validate as linter), how to add pages, and the generator/bm-man roadmap. Part of #952. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
6 tasks
Review feedback on #971: - cloud_info and release_notes duplicated the read-and-substitute logic and its rationale comment; both now call resources.discovery.load_discovery_resource(), the single place that renders promo placeholders (and the single place to extend when more placeholders land) - character-handling doc claimed reindex 'reports conflicts'; it handles them during the scan but emits no conflict report — say what it does Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
Member
Author
Self-review (high effort) — findings and resolutionsRan a 7-angle review pass over the diff (line-by-line, removed-behavior, cross-file tracing, reuse, simplification, efficiency, altitude). Resolutions: Fixed in 97ee1d1:
Considered and rejected:
Cross-file checks came back clean: the lazy 🤖 Generated with Claude Code |
First slice of #610, grown out of the #952 manual work: - src/basic_memory/man/bm.1: hand-written groff overview page (content from the verified bm(1) manual note), plus basic-memory.1 as a .so alias - 'bm man install [--dir]' copies the bundled pages to a man root (default ~/.local/share/man, which manpath(1) derives from ~/.local/bin on PATH on both man-db and BSD man); warns with a one-line MANPATH fix when the root is provably unsearched, stays quiet when manpath is unavailable - verified end-to-end: 'man -M <root> bm' renders, alias resolves - docs/manual-pages.md: lay out the Unix section numbering (1-8, with examples and the crontab(1)/crontab(5) story), document man bm usage, update the roadmap Agents with shell access get 'man bm' as an offline quick reference; the per-tool detail stays in the manual project's section-3 pages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
CI failed because rich wrapped 'not on your manpath' across a line break at the runner's 80-column width; the substring assertion missed it while local wider terminals passed. Collapse whitespace before asserting so the presence and absence checks are immune to wrap position. Verified at COLUMNS=80 and COLUMNS=40. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd87ae0e45
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The repo-side half of #952: the manual-pages flow. The manual itself is live as the
manualproject in the Basic Memory team workspace — 38 pages + theManpageschema, validating 38/38, every example executed against the live service before its page shipped (MCP path = deployed cloud, CLI path = this checkout). This PR lands what belongs in the repo:docs/manual-pages.md— what the manual is, where it lives, page anatomy, how to query it (apropos via metadata search, SEE ALSO traversal), the verification discipline (examples must run; playground rule;verified:stamps;schema-validateas linter), how to add pages, and the roadmap (registry generator,bm man, groff/Add man pages for bm CLI commands #610)plugins/claude-code/schemas/manpage.md— the Manpage Picoschema as an opt-in seed for documentation projects (validated byjust package-check-claude-code)cloud_info/release_notesreturned a literal{{OSS_DISCOUNT_CODE}}placeholder; substitute fromcli.promoand assert no template braces in output. The prior test asserted the placeholder, pinning the bug. Fixes cloud_info and release_notes return unsubstituted {{OSS_DISCOUNT_CODE}} placeholder #958basic-memory sync— now point atbm reindex(part of CLI-only local sync is a dead end: docs reference removed 'basic-memory sync', status --wait can never finish, bm reindex is the undiscoverable answer #959);search_notesdocstring documents the intentionaltotal: 0for vector/hybrid modesWhy building docs this way is worth it
The verification discipline doubled as a live end-to-end smoke test and found six bugs in one pass: #954 (workspace selector silently dropped on create), #955 (
[[None]]forward refs in build_context), #956 (workspace project index never refreshes on miss), #957 (folder/*patterns dead on cloud projects), #958 (fixed here), #959 (CLI-only local sync dead end). Fixes for the routing-layer issues (#954/#956/#957) and #955 are specced in their issues as follow-ups.Verification
pytest tests/mcp/test_tool_cloud_discovery.py -v— 2 passed (regression test asserts substitution)just lint/just typecheck— cleanjust package-check-claude-code— plugin + seed schemas validatebm tool schema-validate manpage --project manual→ 38/38 valid;bm orphans --project manual→ no disconnected pagesRefs #952.
🤖 Generated with Claude Code